Add vector(float16) support - #4501

Pull request overview

Adds end-to-end support for SQL Server vector(N, float16) by negotiating VECTORSUPPORT feature extension version 2, introducing an IEEE-754 binary16 codec, and wiring float16 handling through SqlVector<T> read/write paths (including bulk copy), with accompanying docs and tests.

Changes:

• Negotiate vector feature extension v2 and track negotiated vector capability version (float32/float16) on the connection.
• Add float16 vector support across SqlVector<T>, SqlDataReader, SqlBuffer, SqlParameter, SqlCommand, and SqlBulkCopy, including payload conversion for bulk copy.
• Add unit/manual tests plus docs/snippets/sample updates; expose vector base type + dimensions via DbColumn indexer and register vector in the DataTypes schema collection.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

            // The payload is converted directly rather than through a strongly typed vector,
            // so that .NET Framework, which has no System.Half, can also write to float16
            // destinations.
            return SqlTypes.SqlVector<float>.ConvertPayloadElementType(payload, destinationElementType);

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

        Console.WriteLine($"\nColumn base type:  {column["VectorBaseType"]}");
        Console.WriteLine($"Column dimensions: {column["VectorDimensions"]}");

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

        Console.WriteLine($"\nColumn base type:  {column["VectorBaseType"]}");
        Console.WriteLine($"Column dimensions: {column["VectorDimensions"]}");

                    else if (currentType == typeof(SqlVector<Half>))
                    {
                        value = ((ISqlVector)value).VectorPayload;
                    }
                    #endif

Summary

This adds vector(N, float16) by advertising VECTORSUPPORT v2, introducing a hand-written binary16 codec, teaching SqlVector<T> about System.Half, and switching vector→vector bulk copy to a raw-payload transfer. The engineering is careful, and I want to call out specifically that the endianness and element-size arithmetic is correct throughout — I went looking for a missed (ColumnSize - 8) / 4 and there isn't one. The commit split is clean and the rationale in the description is unusually good.

I have one blocking correctness issue, plus a set of suggestions. Inline comments carry the detail and suggested diffs; this is the map.

Blocking

• SqlBuffer.GetSqlVector<T>() succeeds or throws depending on the row's nullness. The IsNull branch builds a vector for any T without consulting the column's base type, while the non-null branch validates. GetSqlVector<Half>() over a float32 column therefore returns Null for NULL rows and throws NotSupportedException for non-NULL rows in the same result set. Data-dependent rather than schema-dependent, so it is hard to find in testing and impossible to guard against in caller code.

Suggestions

• The codec is not bit-exact against System.Half for NaN, contrary to the description, and the tests are written to step around exactly that case (continue / IsNaN-only). float.NaN carries the sign bit, so widening flips the sign of every NaN relative to System.Half; narrowing canonicalises payloads that (Half)float preserves. Either match System.Half or pin the canonical form with explicit assertions and drop the "bit-exact" claim.
• Bulk copy's vector case uses metadata.scale rather than the scale local that the surrounding code establishes for encrypted columns.
• The widening path skips the magic-number and version validation that the matching path gets via GetCountsOrThrow.
• Capabilities.Float16VectorType is never read anywhere in src/, so a SqlVector<Half> on a v1-negotiated connection fails server-side rather than client-side. (Float32VectorType was already dead in main; this adds a second.)
• The negotiation theory's 0x3 case doesn't test what its comment claims — the simulated server caps the ack itself, so the client's own ceiling check at SqlConnectionInternal.cs:1660 stays untested.
• Docs say narrowing "fails for values outside its range"; the code saturates to ±Infinity and leaves it to the server.
• MetaData is dereferenced without a null check in CreateSourceColumnMetadata.

Things I checked and found correct

Worth recording, since they're the parts most likely to be wrong in a change like this:

• Subnormal widening, signed zero, overflow to infinity, the flush-to-zero boundary (2⁻²⁵ ties to even → 0, 2⁻²⁶ flushes), binary32 subnormal inputs, and the rounding carry into the exponent are all correct. Compiling Manual* on every TFM so the netfx path is under test on .NET too is a good arrangement.
• Bulk copy null handling is correct as-is — GetValueFromSourceRow returns DBNull.Value with isNull = true and ConvertValue returns before ConvertVectorToBaseType. Note a5de733c3 is test-only; it documents behaviour that already worked rather than fixing anything.
• The raw-payload path can't be taken by DataTable, DataRow[], or non-SqlClient DbDataReader sources (they keep ValueMethod.GetValue), and reordering column mappings are safe because sourceOrdinal is the mapped ordinal.
• No unacknowledged breaking changes beyond the three listed: GetDataTypeName is unchanged, GetFieldType/GetProviderSpecificFieldType both route through the single new GetVectorFieldType so they stay consistent, SqlMetaDataFactory.DataTypes only adds a row (gated on MinimumVersionKey), the float32 declaration is deliberately unchanged, and SqlDbColumn's new indexer falls through to base[property].
• No shared mutable state: Float16Converter is stateless and SqlVector<T> is a readonly struct with no static caches.

On testing

Taking as given that CI has no float16-capable server and no Azure SQL DB connectivity, so the manual suite is the only gate that will ever run — I looked at whether it is complete enough for a lab run rather than whether CI covers it. It is substantial: 11 behaviour tests plus the inherited NativeVectorTestsBase matrix, and the sample data is well chosen (Half.MaxValue, Half.Epsilon, -0.0f, exactly-representable eighths). Gaps I'd close:

1. .NET Framework gets none of the NativeVectorTestsBase matrix — NativeVectorFloat16Tests.cs is entirely #if NET. That is where the hand-rolled Manual* codec is the production path.
2. No async coverage for the new representation on any framework, and none at all for float16 on netfx.
3. DataTestUtility.CheckVectorFloat16Supported fails open through the code under test. It reads the probe vector with GetString + JsonSerializer.Deserialize and catches JsonException → false. A driver regression that produces malformed JSON silently skips the whole float16 suite green. Since the manual run is the only gate, that is the wrong failure mode. (Outside this diff, so no inline comment — but worth fixing alongside. It also leaves PREVIEW_FEATURES = ON on the shared test database as a side effect.)
4. Two range tests assert only that some SqlException was thrown; they'd pass on an unrelated failure, and they can't distinguish "client rejects" from "client saturates and server rejects" — which is exactly the ambiguity in the doc wording above.
5. Nothing covers the blocking issue: reading a float32 column as SqlVector<Half>, for a NULL and a non-NULL row.
6. Bulk copy with a dimension-count mismatch between source and destination is uncovered. Mitigating: float32→float32 now routes through the new raw-payload path too and is covered by the existing NativeVectorFloat32Tests, which runs against any vector-capable server — so regression risk to shipped functionality is covered.

Minor

• SqlVector<T>.ToString() changing for existing SqlVector<float> callers is justified and correctly surfaced in the ref assembly and docs, but it is unrelated to float16 — it wants its own release-note entry as a behavioural break, not just an API-list line. Related: GetString() uses JsonSerializer.Serialize, which throws on NaN/Infinity by default, and on .NET Framework that is now the default GetValue() path.
• ConvertPayloadElementType is internal static on SqlVector<T> but never uses T, so callers write SqlVector<float>.ConvertPayloadElementType(...), which reads as though it returns a float32 result.
• On .NET Framework the reader surfaces a float16 column as string while an output parameter surfaces it as SqlVector<float>. Self-consistent, but worth documenting.
• Preprocessor directives in the new code are indented to the surrounding block; the dominant style in these files is column 0.
• ConnectionCapabilities.cs:179 says vectors were "introduced in SQL Server 2022" — pre-existing, but the new Float16VectorType doc sits right beside it.
• Worth confirming the doc/samples build resolves the locally-packed driver: SqlVectorFloat16Example.cs references SqlVector<Half> and GetSqlVector<Half>, which exist in no released package.

_{Review assisted by GitHub Copilot; findings verified against the code at a5de733c3.}

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Float16 compatibility review (head 92d712a)

Checked against the design notes: default V1, opt-in V2, native Half on .NET, JSON plus SqlVector<float> widening on .NET Framework, minimal client conversion, and room for future base types. The basic direction matches. The gaps below are about mixed setups: different negotiated levels, frameworks, and server builds.

Must address

1. Native float16 is sent on V1/Off connections. See the inline comment on SqlCommand.cs.
2. SqlVector<float> in a DataTable cannot be bulk copied into a float16 column. This is the only strongly typed write form on .NET Framework. See the inline comment on SqlBulkCopy.cs.
3. Writes across base types depend on the server. The public SQL docs say float32↔float16 conversion is blocked. See the inline comment on SqlVector.xml.
4. Still open: V2 source → V1/Off (or varchar) bulk copy destination fails on .NET. SqlVector<Half> reaches Convert.ChangeType instead of becoming JSON. Reported in #4501 (review) and not fixed. The same failure happens with a native float16 source and a varchar/nvarchar/json destination column. It also runs against the design goal of moving JSON through bulk copy transparently. A small fix in the CoerceValue string branch (ISqlVector → JSON) would cover all of these.
5. Still open: wide widened values (1,999–3,996 elements) can be reused as parameters. They then send a float32 payload larger than 8,000 bytes. Reported in #4501 (review). Please fail early on the client with a clear message, or document that JSON is the write-back path.
6. Show that the float16 suites really ran. The ADO build 179897 for this PR shows PartiallySucceeded. CheckVectorFloat16Supported also returns false on a JsonException, so a driver bug that breaks JSON output would quietly skip every float16 suite. It also turns on PREVIEW_FEATURES for the shared test database. Raised in #4501 (review) and still present. Please confirm with test results that float16 tests ran (not skipped) on at least one net462 leg and one .NET leg.

Good to have

• On .NET Framework, a DataAdapter/SqlCommandBuilder update of a V2 float16 column fails (inline on SqlDataReader.cs).
• Bulk copy rounds JSON twice (decimal → float32 → float16), so results may differ from server-side JSON conversion (inline on SqlBulkCopy.cs).
• Vector metadata is hard to discover, and it only works on negotiated connections (inline on SqlDbColumn.cs).
• Document that cross-base-type bulk copy of reader payloads behaves differently by framework: rejected on .NET, converted on .NET Framework. Today SqlVector.xml describes only the .NET behavior.

Low priority

• The ConnectionString keyword table in doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml does not list Vector Type Support.
• On .NET Framework, a float16 output parameter returns SqlVector<float> from Value but SqlString from SqlValue (inline).
• JSON → float32 bulk copy lost the client-side 1,998-element check (inline).
• The sample states the wrong minimum version (inline).
• Question: on .NET Framework, will the JSON text a float16 column returns change when an app moves from V1 to V2? Under V1 the server writes the text; under V2 the client builds it. If the text changes, add a note in the docs.

Scope: I read the source only. I did not run builds or tests. All 44 inline threads are already resolved, and I checked the earlier fixes against the current code instead of relying on that status.